/***************************************************************************
 * Copyright 2012-2013 TXT e-solutions SpA
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * This work was performed within the IoT_at_Work Project
 * and partially funded by the European Commission's
 * 7th Framework Programme under the contract ICT-257367.
 *
 * Authors:
 *      Salvatore Piccione (TXT e-solutions SpA)
 *
 * Contributors:
 *        Domenico Rotondi (TXT e-solutions SpA)
 **************************************************************************/
package it.txt.ens.client.subscriber.factory;

import java.io.File;
import java.util.Date;

import it.txt.ens.client.core.factory.ENSBrokerConnectionParametersFactory;
import it.txt.ens.client.subscriber.factory.ENSEventFactory;
import it.txt.ens.client.subscriber.ENSSubscriber;
import it.txt.ens.core.ENSAuthzServiceConnectionParameters;
import it.txt.ens.core.ENSOperation;
import it.txt.ens.core.ENSResource;
import it.txt.ens.core.KeystoreParameters;
import it.txt.ens.core.X509CertificateRetrievalParameters;
import it.txt.ens.schema.request.factory.ENSAuthorisationRequestFactory;
import it.txt.ens.schema.response.factory.ENSAuthorisationResponseFactory;

/**
 * This interface defines methods to create {@link ENSSubscriber} objects.
 * @author Salvatore Piccione (TXT e-solutions SpA - salvatore.piccione AT txtgroup.com)
 * @author Domenico Rotondi (TXT e-solutions SpA - domenico.rotondi AT txtgroup.com)
 *
 */
public interface ENSSubscriberFactory {
    /**
     * Creates an ENS subscriber.
     * 
     * @param subjectID the identifier of the subscriber. <br/>Note that this value must be equal to both:
     * <ul><li>the subject of the authorising capability token </li>
     * <li>the Common Name of the X.509 certificate subject's Distinguished Name</li></ul>
     * It is used to find the capability token
     * granting the least privileges to perform a {@link ENSOperation#publish} on the ENS resource
     * <code>targetResource</code> and to find the private-public keys pairs in the keystore
     * pointed by {@link KeystoreParameters#getKeystorePath()}
     * @param targetResource the resource this client will subscribe to. It is one of the capability search parameters.
     * @param sessionExpiration the preferred session expiration time
     * @param accessRequestBrokerConnParams the parameters to connect to the Access Request Broker
     * @param keystoreParams parameters to read the keystore storing the public-private key pair together with
     * an X.509 certificate
     * @param certParams the parameters to read the X.509 certificate shipped with the public-private key pair to
     * use to digitally sign the authorisation request
     * @param capabilityDirectory the directory where the capability will be searched.
     * @param requestFactory the factory to create the authorisation request
     * @param responseFactory the factory to parse the authorisation response
     * @param connParamsFactory the factory to create the <code>ENSBrokerConnectionParameters</code>
     * holding the parameters to connect to the operative ENS broker.
     * @param eventFactory the factory to create events
     * @return a subscriber
     */
    public ENSSubscriber create (String subjectID, ENSResource targetResource, 
            Date sessionExpiration,
            ENSAuthzServiceConnectionParameters accessRequestBrokerConnParams, KeystoreParameters keystoreParams,
            X509CertificateRetrievalParameters certParams, File capabilityDirectory,
            ENSAuthorisationRequestFactory requestFactory,
            ENSAuthorisationResponseFactory responseFactory,
            ENSBrokerConnectionParametersFactory connParamsFactory, ENSEventFactory eventFactory);
}
